home *** CD-ROM | disk | FTP | other *** search
/ NeXT Enterprise Objects Framework 1.1 / NeXT Enterprise Objects Framework 1.1.iso / NextDeveloper / Headers / foundation / NSDictionary.h < prev    next >
Text File  |  1994-05-13  |  6KB  |  179 lines
  1. /*    NSDictionary.h
  2.     Basic dictionary container
  3.       Copyright 1993, 1994, NeXT, Inc.
  4.     NeXT, March 1993
  5. */
  6.  
  7. #import <foundation/NSArray.h>
  8.  
  9. /* This module implement the 'dictionary' concept.  Featuring:
  10.     - dictionaries are always dynamic (resize themselves by doubling when they reach a certain maximum), so that callers never have to think about allocation;
  11.     - support read only dictionaries;
  12.     - embeds various conveniences;
  13.     
  14.    Generic coding behavior is supplied
  15.     - it preserves class
  16.     - immutable dictionaries are distributed bycopy with their elements also bycopy
  17.     - mutable dictionaries are distributed by reference unless asked bycopy
  18. */
  19.  
  20. /***************    Read Only Abstract Class        ***********/
  21.  
  22. @interface NSDictionary:NSObject <NSCopying, NSMutableCopying>
  23. /* NOTES:
  24.     -copyWithZone: and -copy guarantee an immutable returned value;
  25.         elements are recursively copied with -copyWithZone:
  26.     -isEqual: checks that argument is an NSDictionary;
  27.     If conforming, each item is compared using isEqual:;
  28.     -hash is such that [x isEqual:y] => [x hash] == [y hash];    
  29.      */
  30.  
  31. - (unsigned)count;
  32.     /* Number of (key,associated object) pairs in the dictionary  */
  33.     
  34. - objectForKey:(NSString *)aKey;
  35.     /* Get associated object given its key;
  36.     may return nil */
  37.  
  38. - (NSEnumerator *)keyEnumerator;
  39.     /* Returns an enumerator object to cycle through the keys.
  40.     Note that an object enumerator is also available (see below).
  41.     Updates should not be done during enumeration
  42.     To use:
  43.         NSEnumerator    *enumerator = [collection keyEnumerator];
  44.     id key;
  45.     while (key = [enumerator nextObject]) {
  46.         ... 
  47.     }
  48.     */
  49.   
  50. @end
  51.  
  52. @interface NSDictionary (NSExtendedDictionary)
  53.  
  54. - (BOOL)isEqualToDictionary:(NSDictionary *)other;
  55.     /* Compares 2 dictionaries for exact match;
  56.     Uses isEqual: for comparison predicate; */
  57.  
  58. - (NSString *)description;
  59.     /* Convert to a string, using the "PropertyList" format */
  60.  
  61. - (NSString *)descriptionWithIndent:(unsigned)level;
  62.     /* Convert to a string, using the "PropertyList" format;
  63.     Indent is for human-readibility;
  64.     level==0 means top level; level==1 => 4 spaces */
  65.  
  66. - (NSArray *)allKeys;
  67.     /* returns an array containing all the keys;
  68.     This snapshots the set of keys;
  69.     Order is un-defined; */
  70.  
  71. - (NSArray *)allValues;
  72.     /* returns an array containing all the associated objects;
  73.     This snapshots the set of objects;
  74.     Order is un-defined */
  75.  
  76. - (NSArray *)allKeysForObject:anObject;
  77.     /* Returns all keys for which corresponding object isEqual: given argument;
  78.     Enumerates the dictionary (=> slow, O(N));
  79.     Returns nil if none; otherwise an array of count >= 1 */
  80.     
  81. - (BOOL)writeToFile:(NSString *)path atomically:(BOOL)useAuxiliaryFile;
  82.     /* writes a PList string representation */
  83.  
  84. - (NSEnumerator *)objectEnumerator;
  85.     /* Returns an enumerator object to cycle through the keys.
  86.     Note that a key enumerator is available as the primitive.
  87.     Updates should not be done during enumeration
  88.     To use:
  89.         NSEnumerator    *enumerator = [collection objectEnumerator];
  90.     id object;
  91.     
  92.     while (object = [enumerator nextObject])
  93.         ... 
  94.     */
  95.  
  96. @end
  97.  
  98. /***************    Mutable Abstract Class        ***********/
  99.  
  100. @interface NSMutableDictionary: NSDictionary
  101.  
  102. - (void)setObject:anObject forKey:(NSString *)aKey;
  103.     /* Associate an object for a certain key; 
  104.     If object is nil an exception is raised.
  105.     -retain is applied to the object inserted in the array.
  106.     and -release is applied to previous element, if any;
  107.     The key is always copied by the dictionary */
  108.     
  109. - (void)removeObjectForKey:(NSString *)aKey;
  110.     /* Removes key and associated object from the dictionary;
  111.     Performs -release on previous object if any. */
  112.     
  113. @end
  114.  
  115. @interface NSMutableDictionary (NSExtendedMutableDictionary)
  116.  
  117. - (void)removeAllObjects;
  118.     /* Empties the dictionary; 
  119.     Performs -release on each object removed */
  120.  
  121. - (void)removeObjectsForKeys:(NSArray *)keyArray;
  122.     /* Removes keys and associated objects from the dictionary */
  123.     
  124. - (void)addEntriesFromDictionary:(NSDictionary *)otherDictionary;
  125.     /* inserts all the pairs of other; 
  126.     in case of pairs with same keys, other's pairs win */
  127.  
  128. @end
  129.  
  130. /***************    Immutable Dictionary Creation        ***********/
  131.  
  132. @interface NSDictionary (NSDictionaryCreation)
  133.  
  134. + allocWithZone:(NSZone *)zone;
  135.     /* Create an uninitialized instance of a concrete dictionary;
  136.     substitutes a concrete class if called with NSDictionary;
  137.     +alloc can also be used to that effect */
  138.      
  139. + dictionary;
  140.     /* Creates an autoreleased empty dictionary */
  141.     
  142. + dictionaryWithObjects:(id *)objects forKeys:(NSString **)keys count:(unsigned)count;
  143.     /* Creates an autoreleased dictionary */
  144.  
  145. + dictionaryWithObjects:(NSArray *)objects forKeys:(NSArray *)keys;
  146.     /* objects and keys must have the same number of items;
  147.     All keys must be strings;
  148.     Creates an autoreleased dictionary */
  149.  
  150. - initWithObjects:(id *)objects forKeys:(NSString **)keys count:(unsigned)count;
  151.     /* Designated initializer for immutable dictionaries */
  152.  
  153. - initWithDictionary:(NSDictionary *)otherDictionary;
  154.     /* Performs -retain for each item in otherDictionary */
  155.  
  156. - initWithContentsOfFile:(NSString *)path;
  157.     /* reads a PList string representation;
  158.     returns nil on file error or if not a dictionary */
  159.  
  160. @end
  161.  
  162. /***************    NSMutableDictionary classes        ***********/
  163.  
  164. @interface NSMutableDictionary (NSMutableDictionaryCreation)
  165.  
  166. + allocWithZone:(NSZone *)zone;
  167.     /* Create an uninitialized instance of a concrete dictionary;
  168.     substitutes a concrete class if called with NSMutableDictionary;
  169.     +alloc can also be used to that effect;
  170.     -dealloc empties dictionary using -removeAllObjects before de-allocating */
  171.      
  172. + dictionaryWithCapacity:(unsigned)numItems;
  173.     /* Creates an autoreleased mutable dictionary */
  174.  
  175. - initWithCapacity:(unsigned)numItems;
  176.     /* Designated initializer for mutable dictionaries */
  177.  
  178. @end
  179.